…entation)

Incorporates reviewer request: the work on this feature kicks off with a
Story that authors the behave `.feature` files for unified mode BEFORE
the feature is implemented. The intent is to keep test-shape authorship
free of implementation bias and to surface any architectural gaps early.

Adds two JIRAs to the spike doc's proposed-JIRAs list, bringing the
total from 7 to 9:

1. LCORE-???? (Story, inserted first) — E2E feature files for unified
   mode (no step implementation). Authors Gherkin scenarios against the
   spec doc's R1..R11 requirements. Explicitly forbids reading the
   implementation JIRAs or the synthesizer code while authoring.
   behave marks resulting steps as undefined; test-e2e still green
   (undefined scenarios are reported, not failed).

2. LCORE-???? (Task, inserted after the migrate-e2e-configs Story) —
   Implement behave step definitions for the kickoff feature files.
   Takes the Gherkin as-is (does not water down the tests to fit
   implementation). Blocked by the kickoff ticket plus the feature-
   implementation tickets (schema + synthesizer, migration tool, LS
   container entrypoint).

Filing both tickets together (rather than filing only the kickoff and
"letting the step-def ticket appear later") makes the dependency chain
explicit from the start and ensures the step-def work is not forgotten.

No other JIRAs change scope. The PR template is updated to reflect the
new count and to widen the "Full JIRA list" link range to cover both
new sections.

Per docs/contributing/howto-organize-poc-output.md (line 9), the convention
is `poc-results/`. The LCORE-836 PoC bundle was written under
`poc-evidence/` by mistake; rename to match the documented convention.

Also updates references in the spike doc and the PoC README.

Revisions arising from a re-read of the spike doc.  Spike doc:

- Add a "Design options A-E" explainer section near the top so readers
  encounter the option short names + one-line summaries before any
  decision references them.  Drop options D and F (previously dropped
  without scoring) entirely; renumber the survivors so letters are
  consecutive: old E (Profiles) -> new D, old G (Kustomize patches)
  -> new E.  References throughout the doc updated accordingly.
- Restructure Decision S1: one standalone option per row in the
  choice table, no more "B+C" / "C+E" composite labels.  Intro prose
  reduced to a link to the scoring section; recommendation spells out
  C (base shape) + D (optional profile layer).
- Replace Decision S2 with a single Q3/Q4 deprecation recommendation.
- Simplify Decision S3 to the "anything apart from Konflux?" framing.
- Decision T6: refer to profiles as "Option D layer" (was E).
- Decision T7: define "round-trip" in plain English on first use;
  recommend `default` as the field's default value; remove the
  reviewer-naming question.
- Decision T8: drop the Tekton-pipelines framing, Konflux only;
  name @radofuchs explicitly as the owner.
- Delete Decision T9 entirely (it was informational, not a decision).
  Its content is now an expanded bullet under "Findings discovered
  during PoC" covering the underlying library-client API constraint,
  three concrete implementation consequences, and a closing note on
  why a dict-only path isn't worth pursuing.
- PoC results section:
  - Drop the "Level 3'" reference (the other levels are never defined
    and the term carries no value here).
  - Rephrase the smart-migration bullet as deferred future work
    pointing at the spec doc's Open Questions.
  - Rewrite the provider_id naming-collision text in plain English.
  - Fix the evidence link block: was pointing at
    poc-evidence/library-mode/ (wrong directory after the earlier
    rename) and listed lightspeed-stack-unified-library.yaml as if
    it lived inside that subdir, whereas it actually sits one level
    up.  Each file now linked at its real location.
  - Rename "Surprise discovered during PoC" -> "Findings discovered
    during PoC".
  - Remove the stale "(Decision T9)" attribution.
- Rename "Current architecture (before LCORE-836)" ->
  "Current architecture" (the parenthetical added no information).
- "Design alternatives considered": add intro paragraph that
  explicitly frames the table as scoring; expand each of the 12
  attribute names from a short phrase to a full definition with
  high/low criteria; table columns renumbered A, B, C, D, E
  (was A, B+C, C+E, E, G); closing paragraph swaps "E layered on top
  of C" -> "D layered on top of C".
- Overview's recommendation paragraph: link target updated from
  Design options A-G to A-E; Option E -> Option D.

Spec doc:

- Realign the deprecation schedule with the new spike S2
  recommendation (Q3/Q4 warnings, end-of-Q4 removal).  Trim "subject
  to PM confirmation against the actual release calendar." -> "subject
  to PM confirmation."
- Rename the stale "see PoC surprise in the spike doc" reference to
  point at the new "Findings discovered during PoC" section.

…nchor

Spec doc:
- R6 reworded: it is true that LCORE itself does not resolve env refs
  on disk, but `native_override` and the dumb migration tool can carry
  literal secrets from a legacy `run.yaml`.  The previous wording made
  a stronger claim than the design can honour, so it has been narrowed
  to "secrets LCORE emits are not resolved on disk".
- R10 strengthened: the synthesized file must be created with mode
  0600 via an explicit create flag (not umask), so that when
  `native_override` or a migrated `run.yaml` does carry a literal
  secret, the file is not world-readable.
- "Security considerations" section rewritten to (a) drop the
  inaccurate "no secrets written to disk" blanket statement,
  (b) acknowledge that `native_override` and dumb-mode migration
  output may contain literal secrets, (c) mandate 0600 on the
  synthesized file, (d) recommend the migration tool's help / docs
  advise operators to replace literal secrets with `${env.<VAR>}`
  refs before or after migration, (e) note that LS's own
  `replace_env_vars()` (in `llama_stack.core.library_client`) is
  the in-memory resolver at LS startup.

Spike doc:
- Fix broken in-page anchor on line 166: the target heading is
  "### Merge semantics — worked examples", and GitHub renders that
  heading's anchor with a double hyphen
  (`#merge-semantics--worked-examples`) because the em-dash is
  stripped and the surrounding spaces both become hyphens.  Link
  display text now matches the heading exactly as well.

CodeRabbit flagged twelve fenced code blocks in the spike doc that
were missing blank lines before or after them (markdownlint MD031).
Applied via `markdownlint-cli2 --fix`.  No content change — purely
blank-line insertions around `\`\`\`text` and `\`\`\`yaml` fences in
the Proposed JIRAs section and Appendix B.

Line numbers of section headings (S1-T8, ## Proposed JIRAs) are
unchanged.  ## PoC results moved from L614 to L642 because the
auto-fix added blank lines inside the JIRAs section that precedes
it.

In response to @tisnik's review comment about future-proofing the
unified config schema against a backend swap, plus the project
direction to migrate from Llama Stack to Pydantic AI over time.

S5 extends S1 — it does NOT replace it.  Option C + optional D
remains the recommended overall shape.  S5 only decides *where* the
backend-agnostic high-level keys (`inference.providers` today;
later `rag.providers`) live in the operator-facing YAML hierarchy:
at the top level, not under the `llama_stack` subtree.  LS-specific
knobs (`native_override`, `profile`, `baseline`) stay under
`llama_stack.config` unchanged.

Confidence is 70%; the recommendation is provisional until a
research pass on Pydantic AI's actual config surface lands.  A
TODO is captured in the decision body so the spike author resolves
the per-provider `type:` vocabulary question post-research.

If S5 is adopted, the existing "Unified llama_stack.config schema +
synthesizer" implementation JIRA's scope shifts to ship the
top-level shape from day one.  No new JIRA is added.

Spike doc:

- Adds a new finding to "Findings discovered during PoC" calling
  out that the PoC's safety-shield validation was vacuous: the
  `native_override` registered `llama-guard` with
  `provider_shield_id: openai/gpt-4o-mini` — an OpenAI chat model,
  not a Llama Guard checkpoint, so the evidence row "`native_override`
  took effect" only proves the key landed, not that a real shield
  gated any query.  Caught by CodeRabbit on
  `poc-results/library-mode/synthesized-run.yaml:110`.  The
  implementation JIRA's e2e coverage must exercise a real Llama
  Guard model (e.g. `meta-llama/Llama-Guard-3-8B`).

- Updates Decision S5 with the Pydantic AI research findings from
  2026-05-20:
  - Drops the "future `rag.providers`" lift from the proposed table;
    research confirms Pydantic AI has no RAG / vector-store
    abstraction and no public roadmap signal one is coming in 6–12
    months.  RAG, safety/shields, vector storage all stay under
    `llama_stack.config`.
  - Adds a "Pydantic AI research findings" subsection citing the
    full report (now in `poc-results/pydantic-ai-research.md`)
    and the researcher's confidence numbers per concept: ~75% for
    `inference`, ~25% for RAG, ~20% for safety, ~60% for MCP.
  - Resolves the `inference.providers[].type` vocabulary TODO:
    keep LCORE's existing Literal vocabulary
    (`openai`, `azure`, `sentence_transformers`, …); each
    backend-specific synthesizer translates to its target shape.
  - Raises decision confidence from 70% to 75%; reservation is
    now research-bounded (Pydantic AI pre-V2 minor-surface churn,
    very low per their stated policy) rather than
    information-gap-bounded.
  - Adds a note that Pydantic AI V2 timing ("April 2026 at the
    earliest" — has not shipped as of 2026-05-20) likely overlaps
    LCORE's migration window; re-validate when V2 ships.

Adds the full research report under
`poc-results/pydantic-ai-research.md` (Llama Stack ↔ Pydantic AI
concept mapping, dated 2026-05-20) so the spike doc's link to it
resolves and so the evidence travels with the spike.

@sbunciak confirmed the two open strategic asks in PR review on
2026-05-20.  Recording the outcomes:

Spike doc:
- S2 (deprecation timeline): decided — warnings in 0.6 (no breaking
  change), legacy path removed in 0.7; tentative releases 0.6 end of
  June 2026, 0.7 end of September 2026.  Drops the "@sbunciak to
  confirm" trailing ask now that it is resolved.
- S3 (downstream implications): answered — the downstream consumers
  to account for are RHEL LS (@major) and RHDH (@elsony), both
  running LCORE in library mode.  RHEL LS is flexible on switching to
  server mode or reorganizing its run.yaml handling; RHDH pending
  confirmation from @elsony.  No design change required — library
  mode is already the primary path.

Spec doc (the permanent reference picks up only the S2 outcome, since
it is a real implementer-facing requirement; the S3 consumer names are
a decision-closure detail that lives in the spike):
- R2: corrected — the startup WARN ships in 0.6 (same release as
  unified mode), not "one release after unified mode lands"; legacy
  removed in 0.7.
- Deprecation schedule: replaced the Q3/Q4 placeholder with the
  confirmed 0.6 warnings / 0.7 removal plan and tentative dates.

Decision S5 moves the high-level inference section to the top level of
lightspeed-stack.yaml, but the spec doc still described it nested under
llama_stack.config (pre-S5). The schema JIRA points implementers at the
spec doc, so this had to be reconciled before filing.

Resolving S5 surfaced a name collision: the root `Configuration` model
already has a top-level `inference:` field (`InferenceConfiguration` —
`default_model` / `default_provider` for query-time routing), always
present via default_factory. Rather than add a competing key, S5's
provider list is added to that existing section as
`inference.providers`. Detection therefore keys on `inference.providers`
being non-empty (the section always exists) OR `llama_stack.config`
present — a "synthesis input" set rather than a single trigger key.

Spec doc:
- "What" / Key shape: inference is a top-level section (existing
  `inference:` extended with `providers`); native_override / profile /
  baseline stay under llama_stack.config.
- R1, R9, R11: unified shape = synthesis inputs (`inference.providers`
  and/or `llama_stack.config`); R9 documents extending
  InferenceConfiguration + the root-model validator.
- New "Mode detection" subsection: full combination matrix (unified /
  legacy / error / remote), url orthogonality, config_format_version
  soft-coupling.
- Pydantic block: drop UnifiedInferenceSection; show
  InferenceConfiguration gaining `providers`, UnifiedLlamaStackConfig
  reduced to backend-specific knobs, and the mutual-exclusion
  model_validator relocated to the root Configuration model.
- Synthesizer pipeline, _load_library_client fork, error handling,
  config-pattern note, and the key-files table all updated to the
  synthesis-input model.
- Open Questions: future rag/safety/storage sections stay under
  llama_stack.config per S5 + the Pydantic AI research.

Spike doc:
- S5: add the collision-resolution paragraph (lands in the existing
  inference section) and the mode-detection knock-on (synthesis-input
  signal, expands T1).
- T1: note the S5 knock-on to shape detection.
- Schema JIRA: extend InferenceConfiguration, drop UnifiedInferenceSection,
  root-model validator, synthesis-input detection.
- Appendix A (PoC files-changed): annotate that the implementation
  follows S5, not the PoC's UnifiedInferenceSection layout.

- E2E feature-files kickoff JIRA: widen the mutual-exclusion scenario
  from the old "llama_stack.config + library_client_config_path" to the
  synthesis-input model (a non-empty inference.providers OR a
  llama_stack.config block, each combined with
  library_client_config_path must fail). Also note top-level
  inference.providers as the unified boot path. Keeps the to-be-filed
  ticket precise post-S5.
- Decision S5: fix the research-report link — stale display text
  (compass_artifact_…) over an absolute URL replaced with a relative
  link to poc-results/pydantic-ai-research.md, matching the doc's other
  references. Surfaced by a consistency audit.

The feature-design process on upstream/main groups proposed JIRAs into an
Epic tree and expects a spec-doc "Acceptance test surface" section that
drives the e2e-kickoff feature files. Conform this PR's artifacts.

Proposed JIRAs — group into three Epics by aspect (the process names
Implementation / Docs / Tests as the grouping aspects for larger
features; this feature spans all three), ordered Implementation-first:
- Epic "Unified-config implementation": schema + synthesizer, migration
  tool, LS entrypoint + deployment, deprecation WARN.
- Epic "E2E and test-config coverage": e2e kickoff, e2e/integration
  config migration, step definitions.
- Epic "Documentation": docs migration, reference profiles.
Implementation leads by maintainer preference; this overrides the
config's e2e_kickoff_position=first default (the kickoff is still the
first child of the Tests Epic, and its no-dependency / author-before-impl
intent is preserved in the ticket and its blocking relationships). Each
Epic carries Goals/Scope prose (becomes the filed Epic description); the
nine tickets are demoted to #### H4 children. Verified with
file-jiras.sh --parse-only: epic_grouped, 3 Epics + 9 children, every
child's parent_epic_file routes to its Epic, types preserved, no [LINT-*].

Spec doc — add an "Acceptance test surface" section (R1..R11 -> observable
behavior -> verified-by), the documented source-of-truth that drives the
e2e-kickoff feature files. Point the kickoff JIRA's agentic instruction at
it and trim the kickoff's inline scenario list, which is now consolidated
in the table (removes the duplication that could drift from the
requirements). No decision or requirement changed — pure consolidation.

Each of the three proposed-JIRA Epic blocks now carries a "Spec doc:"
link to the spec doc's predicted permanent location on main
(github.com/lightspeed-core/lightspeed-stack/blob/main/...). So the
filed Epics give a Jira reader a clickable pointer to the full design.

The URL 404s until this spike PR merges to main; that's acceptable since
the Epics are acted on post-merge. The feature ticket (LCORE-836)
description gets the same URL later, at /spike-finalize, when the URL is
guaranteed live. In-repo cross-references and the child tickets' agentic
instructions deliberately stay as repo-relative paths (rot-proof, correct
for an agent working in a checkout).

JIRAs filed (Epics 2335/2340/2344, children 2336–2339, 2341–2343,
2345–2346, all under LCORE-836 via "Informs"). Replace every LCORE-????
placeholder in the Proposed JIRAs section with the real key:

- The nine `#### LCORE-????` ticket headings -> `#### LCORE-NNNN:` (the
  filed-key form file-jiras.sh recognises for re-sync).
- The `<!-- key: -->` metadata comments.
- Cross-references resolved by what they point at: kickoff Blocks /
  step-defs Blocked-by (-> 2341 kickoff, 2336 schema, 2337 migration,
  2338 entrypoint, 2343 step-defs).

No LCORE-???? placeholders remain. /spike-finalize will verify no orphans
post-merge.